/**
 * 文件：UserService.java
 * 作者：赵子樵
 * 完成度：完成
 * 最后修改日期：2023-7-1 12:20
 */

package com.gomokult.service;

import com.gomokult.entity.User;
import com.gomokult.exception.IllegalOperationException;
import com.gomokult.exception.InvalidIDException;
import com.gomokult.exception.UserRegisteredException;

/**
 * 提供与账户系统相关的服务接口。
 * @author 赵子樵
 */
public interface UserService {
	/**
	 * 以电子邮箱{@code email}注册一个用户名为{@code nickname}，密码为{@code password}的账号。
	 * @param email 注册账号所使用的邮箱
	 * @param nickname 用户昵称
	 * @param password 用户密码
	 * @return 一个整数，表示数据库为该用户分配的ID
	 * @throws UserRegisteredException 当邮箱{@code email}已被注册时
	 */
	int registerUser(String email, String nickname, String password) throws UserRegisteredException;

	/**
	 * 尝试使用密码{@code password}登录邮箱为{@code email}的账号。
	 * @param email 账号的电子邮箱
	 * @param password 用户输入的密码
	 * @return 若登录成功，返回一个整数，表示该用户的ID；否则返回{@code 0}
	 */
	int loginVerify(String email, String password);
	
	/**
	 * 获取ID为{@code userID}的用户的个人信息（不包含密码字段）。
	 * @param userID 待查询的用户ID
	 * @return 一个{@code User}对象，记录了目标用户的个人信息。为了保证账户安全，{@code User.password}属性应始终为{@code null}
	 * @throws InvalidIDException 当ID无效或不存在时
	 */
	User getUserInfo(int userID) throws InvalidIDException;
	
	/**
	 * 获取邮箱为{@code email}的用户的个人信息（不包含密码字段）。
	 * @param email 待查询的用户邮箱
	 * @return 一个{@code User}对象，记录了目标用户的个人信息。为了保证账户安全，{@code User.password}属性应始终为{@code null}
	 * @throws InvalidIDException 当邮箱无效或不存在时
	 */
	User getUserInfo(String email) throws InvalidIDException;
	
	/**
	 * 以ID为{@code executor}的用户身份更新用户信息。此方法接收一个用户对象{@code pattern}，然后将ID为{@code pattern.userID}的用户信息更新为{@code pattern}中的属性值。<p>
	 * * 注意，此方法只能修改用户的个人信息。{@code winGamesCount}、{@code totalGamesCount}等由系统维护的无关属性将被忽略；{@code password}等涉及账号安全的属性也作忽略处理。
	 * @param executorID 执行修改操作的用户的ID。该参数是原本是为了能够让管理员也可以修改用户信息。但由于管理员系统在进一步的需求分析中被弃用，该参数目前只起到验证操作的执行者是否为用户本身的作用。如果{@code executorID}与{@code pattern}中所描述的ID字段不一致，则抛出{@code IllegalOperationException}
	 * @param pattern 记录了需要被修改成的用户信息，其ID字段表示需要被修改信息的用户
	 * @throws InvalidIDException 当给定的ID无效或不存在时
	 * @throws IllegalOperationException 当用户不具备修改指定用户个人信息的能力时
	 * @throws UserRegisteredException 当用户填写的邮箱已被注册时
	 */
	void setUserInfo(int executorID, User pattern) throws InvalidIDException, IllegalOperationException, UserRegisteredException;
}
